Skip to content

fix(notebooks): fine-tune notebook fits temperatures outside runtime clamp, so served calibration differs (#637) - #642

Merged
NandhaKishorM merged 3 commits into
NandhaKishorM:mainfrom
Sarthak-Pandey:fix/temperature-calibration-bounds
Oct 1, 2026
Merged

NandhaKishorM merged 3 commits into
NandhaKishorM:mainfrom
Sarthak-Pandey:fix/temperature-calibration-bounds

Conversation

@Sarthak-Pandey

Copy link
Copy Markdown

Summary

Fixes #637.

This PR fixes a discrepancy between the temperature produced during post-training calibration and the temperature used by the production laya.Agent.

In notebooks/laya_finetune_typed_decisions_2xT4_kaggle.ipynb, fit_one_temp() previously clamped fitted temperatures using:

torch.clamp(log_t.exp(), 0.1, 10.0)

However, when a checkpoint is loaded in production, laya.Agent (laya/agent.py) passes the stored temperature through clamp_temperature() (laya/common.py), which enforces the serving bounds:

TEMP_MIN = 0.5
TEMP_MAX = 5.0

This meant that the notebook and production environment could use different temperature values.

The Discrepancy

If fit_one_temp() produced a temperature outside the serving range—for example, 9.886 or 7.10—that value could be persisted to rl_agent_config.json unchanged.

When the checkpoint was subsequently loaded, laya.Agent would clamp the value to the production range. For example:

Fitted temperature:  9.886
Stored temperature:  9.886
Served temperature:  5.0

As a result, the calibration performed during fine-tuning did not necessarily reflect the behavior of the model after deployment:

fit != serve

This could also result in a warning when loading checkpoints containing temperatures outside the serving bounds.

Changes

1. Kaggle Fine-Tuning Notebook

Updated notebooks/laya_finetune_typed_decisions_2xT4_kaggle.ipynb to use the canonical temperature bounds from laya.common.

  • Imported TEMP_MIN and TEMP_MAX.
  • Updated fit_one_temp() to clamp fitted temperatures using:
torch.clamp(log_t.exp(), TEMP_MIN, TEMP_MAX)

This ensures that the temperature produced during calibration is already within the same range enforced during serving.

2. Regression Test

Added test_notebook_fit_one_temp_clamps_to_common_bounds to tests/test_calibration_persistence.py.

The test extracts fit_one_temp() from the notebook and verifies that its output remains within [TEMP_MIN, TEMP_MAX], including when presented with extreme logit inputs.

This prevents future changes from reintroducing a mismatch between calibration and serving behavior.

Verification

Ran syntax and compilation checks successfully:

python -m compileall -q laya/ tests/

@NandhaKishorM

Copy link
Copy Markdown
Owner

Holding: Please split this PR to keep the notebook temperature clamp and test only, and drop the external php links and unicode-escape churn.

@Sarthak-Pandey

Copy link
Copy Markdown
Author

Thanks for the feedback. I’ve updated PR #642 as requested. The PR is now limited to the notebook temperature clamp using TEMP_MIN/TEMP_MAX and the corresponding regression test. I also removed the unrelated PHP/Laravel documentation changes and Unicode/serialization churn.
I’ve re-run the relevant tests and validation checks successfully, and the updated diff is now scoped only to issue #637.

@Bruce-Yii Bruce-Yii left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is now exactly the split you asked for, and the remaining change is right. I checked it against current main rather than taking the description on faith.

The bug is real, and the mismatch is worse than "differs"

notebooks/laya_finetune_typed_decisions_2xT4_kaggle.ipynb clamped the fitted temperature to (0.1, 10.0), while the runtime it has to agree with bounds the same quantity differently:

laya/common.py:552  TEMP_MIN = 0.5
laya/common.py:553  TEMP_MAX = 5.0
laya/common.py:556  def clamp_temperature(t, lo=TEMP_MIN, hi=TEMP_MAX)

So a temperature the notebook declared fitted and persisted was re-clamped on the way out — the notebook's own fit was the thing being silently discarded, not just a rounding difference.

RED → GREEN on current main

I took the PR's two files onto 6d942c9 and ran only that suite, so both arms are the same tree with one file swapped.

tree result
main notebook + this PR's test 1 failed, 5 deselected — AssertionError: 10.0 not less than or equal to 5.0
this PR's notebook + its test 6 passed, 45 subtests passed

The failure is the assertion the fix exists to support, on the high side, with the real fitted value — not an import or a fixture error.

It also merges clean, which is the part that would otherwise cost a round trip

The PR's base is 9d95567 (v0.3.21), so the diff view shows 226 files. That is base age, not scope — the authored change is the two files and +23/-4:

notebooks/laya_finetune_typed_decisions_2xT4_kaggle.ipynb |  6 +++---
tests/test_calibration_persistence.py                     | 21 +++++++++++++++++++-

Applying just those two files to 6d942c9 merges with no conflict.

One non-blocking note

The new check pins only the high bound. I looked for an input family that drives the fit below TEMP_MIN = 0.5 and could not construct one — across a sweep of logit and target ranges the lowest value reachable under main's (0.1, 10.0) clamp was 0.519. So the low side may well be unreachable through this code path, which is why I am not asking for anything here. Flagging it only so the asymmetry is a decision rather than an oversight if that turns out to change.

Approving.

@NandhaKishorM
NandhaKishorM merged commit 6ea5849 into NandhaKishorM:main Oct 1, 2026
@NandhaKishorM

Copy link
Copy Markdown
Owner

Merged for 0.3.23.

Verified on the integrated branch, not on the PR in isolation: every suite in the ci.yml test lane plus the pytest lane green, compileall clean, and a decision diff against main on the real english and multilingual checkpoints (72 answers over choice, score and noul, short and long states, budgeted and predict_long) showing zero decision flips and a max probability delta of 0.000000.

Thank you.

thread3d added a commit to thread3d/laya that referenced this pull request Oct 2, 2026
The notebook rewrite removes the `%%writefile` cell this guard scraped for the
config export and for NandhaKishorM#642's temperature clamp. Point both at
laya.finetune.train_rlcd / fit_temperature, which own that code now, so the
guard still runs instead of erroring on an empty cell list.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Fine-tune notebook fits temperatures outside the runtime clamp, so the served calibration differs from the fitted one

3 participants